package com.compunit.composite.core.interfaces.cx;

import java.io.IOException;
import java.net.URL;

/**
 * <code>ICxImporter</code> defines the interface of
 * an utility importing unit that provides the ability
 * to import all the essential information of a single
 * component using its <code>cx</code> file.
 * <p>
 * <code>ICxImporter</code> first processes the data
 * using the provided files via <code>process</code>
 * method. It then caches all the information internally
 * for later retrieval. A cache clean up can be done
 * via the <code>cleanup</code> method to erase all
 * the cached data.
 * <p>
 * <code>ICxImporter</code> can be directly reused to
 * process a second component. It internally performs
 * a cache clean up before the subsequent processing.
 * <p>
 * <code>ICxImporter</code> is meant to be used in a
 * strictly single-threaded environment. There is no
 * concurrency support at all.
 *
 * @author Yi Wang (Neakor)
 * @version Creation date: 10-27-2009 22:58 EST
 * @version Modified date: 11-21-2009 18:39 EST
 */
public interface ICxImporter {

	/**
	 * Process the <code>cx</code> file linked by the
	 * given URL.
	 * @param url The <code>URL</code> links to the
	 * <code>cx</code> file.
	 * @throws IOException If file reading is interrupted.
	 */
	public void process(final URL url) throws IOException;
	
	/**
	 * Retrieve the name of the component that has been
	 * processed.
	 * @return The <code>String</code> component name.
	 */
	public String getName();
	
	/**
	 * Retrieve the activation order of component units.
	 * @return The <code>Iterable</code> of <code>ICxUnit</code>.
	 */
	public Iterable<ICxUnit> getActivation();
	
	/**
	 * Retrieve all the cx mapping definitions.
	 * @return The <code>Iterable</code> of all the
	 * <code>ICxMapping</code> data structures.
	 */
	public Iterable<ICxMapping> getMappings();

	/**
	 * Retrieve all the cx binding definitions.
	 * @return The <code>Iterable</code> of all the
	 * <code>ICxBinding</code> data structures.
	 */
	public Iterable<ICxBinding> getBindings();
	
	/**
	 * Clean up all the cache data.
	 */
	public void cleanup();
}
